Get top articles by engagement, paginated.

12 May 2026
7 Minutes to read
Contributors

Print
Share
Dark
Light

Get top articles by engagement, paginated.

Updated on 12 May 2026
7 Minutes to read
Contributors

Print
Share
Dark
Light

Article summary

Did you find this summary helpful?

Thank you for your feedback!

Get

/v3/projects/{project_id}/analytics/articles/top

Returns a paginated list of articles ranked by engagement metrics such as views, reads, likes, and dislikes. Supports sorting by any metric column and ordering. Use this endpoint to identify your highest-performing content. Requires ViewAnalytics permission.

Security

OAuth

All V3 endpoints require a Bearer token. Generate tokens in the Document360 portal under Settings > API Tokens. Tokens are project-scoped, require the customerApi scope, and do not expire by default. Tokens can be revoked at any time from the portal. Include the token in every request: Authorization: Bearer <your-token>. Alternatively, use the Authorize button below to sign in via OAuth2 Authorization Code flow with PKCE.

FlowAuthorization Code

Authorization URLhttps://identity.document360.net/connect/authorize

Token URLhttps://identity.document360.net/connect/token

Scopes:

customerApiDocument360 Customer API

Path parameters

project_id

string (uuid) Required

The unique identifier of the project. Retrieve project IDs from GET /v3/projects.

Example9a3b4c5d-6e7f-8a9b-0c1d-2e3f4a5b6c7d

Query parameters

start_date

string (date-time)

Start of the date range (inclusive) in ISO 8601 format.

end_date

string (date-time)

End of the date range (inclusive) in ISO 8601 format.

project_version_id

string (uuid)

Optional project version ID to scope results. Retrieve from GET /v3/projects/{projectId}/versions.

Example9a3b4c5d-6e7f-8a9b-0c1d-2e3f4a5b6c7d

lang_code

string

ISO 639-1 language code (e.g., en, fr). Defaults to the project's primary language if omitted.

Pattern^[a-z]{2}(-[A-Z]{2})?$

Exampleen

page

integer (int32)

Page number (1-based). Defaults to 1.

Minimum1

Default1

page_size

integer (int32)

Number of results per page. Defaults to 25. Maximum 100.

Minimum1

Maximum100

Default25

sort_by

string

Column to sort by: views, reads, likes, dislikes. Defaults to views.

Default"views"

sort_order

string

Sort direction: asc or desc. Defaults to desc.

Default"desc"

Responses

200

Top articles by engagement

{
  "data": [
    {
      "article_id": "9a3b4c5d-6e7f-8a9b-0c1d-2e3f4a5b6c7d",
      "title": "Getting Started with Single Sign-On",
      "slug": "getting-started-with-single-sign-on",
      "views": 1250,
      "reads": 890,
      "likes": 45,
      "dislikes": 3,
      "time_spent_seconds": 18200,
      "feedbacks": 12,
      "last_viewed_at": "2025-09-10T14:32:00Z",
      "last_updated_at": "2025-08-25T09:15:00Z"
    },
    {
      "article_id": "b4c5d6e7-8f9a-0b1c-2d3e-4f5a6b7c8d9e",
      "title": "API Authentication Guide",
      "slug": "api-authentication-guide",
      "views": 980,
      "reads": 720,
      "likes": 38,
      "dislikes": 1,
      "time_spent_seconds": 14500,
      "feedbacks": 8,
      "last_viewed_at": "2025-09-10T11:20:00Z",
      "last_updated_at": "2025-07-12T16:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 25,
    "total_count": 156,
    "has_more": true,
    "next_cursor": null
  },
  "success": true,
  "request_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "errors": null,
  "warnings": null
}

Expand All

object

Paginated API response containing a list of items.

data

Array of object (TopArticleResponse)

List of items for the current page.

object

Article ranked by engagement metrics.

article_id

string | null

Unique identifier of the article.

Example9a3b4c5d-6e7f-8a9b-0c1d-2e3f4a5b6c7d

title

string | null

Title of the article.

ExampleGetting Started with Single Sign-On

slug

string | null

URL-friendly slug of the article.

Examplegetting-started-with-single-sign-on

views

integer (int32)

Total page views for this article.

Example1250

reads

integer (int32)

Total reads for this article.

Example890

likes

integer (int32)

Total likes for this article.

Example45

dislikes

integer (int32)

Total dislikes for this article.

Example3

time_spent_seconds

integer (int32)

Total time spent reading this article, in seconds.

Example18200

feedbacks

integer (int32)

Total number of feedback submissions for this article.

Example12

last_viewed_at

string (date-time)

Date and time the article was last viewed.

Example2025-09-10T14:32:00Z

last_updated_at

string (date-time)

Date and time the article was last updated.

Example2025-08-25T09:15:00Z

pagination

object

Pagination metadata.

page

integer (int32)

Current page number (1-based). Returns 0 when using cursor-based pagination.

page_size

integer (int32)

Number of items per page.

total_count

integer (int64) | null

Total number of items across all pages. Only populated when include_total_count=true is specified in the request.

has_more

boolean

Whether additional pages are available.

next_cursor

string | null

Opaque cursor to retrieve the next page of results. Pass this value as the cursor query parameter. Null when there are no more pages.

success

boolean

Whether the API request was successful.

request_id

string

Unique identifier for request tracing and correlation.

Min length1

errors

Array of object (ApiError) | null

List of errors if the request failed.

object

Represents an error returned by the API.

code

string

Machine-readable error code (e.g. VALIDATION_ERROR, RESOURCE_NOT_FOUND).

Min length1

message

string

Human-readable error message.

Min length1

field

string | null

The request field that caused the error, if applicable.

details

string | null

Additional context about the error.

warnings

Array of object (ApiWarning) | null

List of non-fatal warnings from the request.

object

Represents a non-fatal warning from the API.

code

string

Machine-readable warning code.

Min length1

message

string

Human-readable warning message.

Min length1

401

Authentication token is missing or invalid.

Headers

WWW-Authenticate

string

Indicates the authentication scheme required. Returns `Bearer` with optional `error` and `error_description` parameters per RFC 6750.

Missing or invalid token

Authentication token is missing or invalid.

{
  "type": "https://developer.document360.com/errors/unauthorized",
  "title": "Unauthorized.",
  "status": 401,
  "detail": "The authentication token is missing or has expired.",
  "instance": null,
  "trace_id": "req_abc123def456",
  "errors": [
    {
      "code": "UNAUTHORIZED",
      "message": "Bearer token is missing or invalid.",
      "field": null,
      "details": null
    }
  ],
  "warnings": null
}

Expand All

object

RFC 7807 Problem Details response for V3 API errors. Content-Type: application/problem+json

type

string

URI reference identifying the error type (links to documentation).

Min length1

title

string

Short human-readable summary of the error type.

Min length1

status

integer (int32)

HTTP status code.

detail

string | null

Human-readable explanation specific to this occurrence.

instance

string | null

URI of the request that generated the error.

trace_id

string | null

Request trace identifier for correlation.

errors

Array of object (ApiError) | null

Structured list of specific errors (extension field).

object

Represents an error returned by the API.

code

string

Machine-readable error code (e.g. VALIDATION_ERROR, RESOURCE_NOT_FOUND).

Min length1

message

string

Human-readable error message.

Min length1

field

string | null

The request field that caused the error, if applicable.

details

string | null

Additional context about the error.

warnings

Array of object (ApiWarning) | null

Non-fatal warnings (extension field).

object

Represents a non-fatal warning from the API.

code

string

Machine-readable warning code.

Min length1

message

string

Human-readable warning message.

Min length1

422

Validation failed (e.g., invalid date range or sort column).

Validation failed

The request body contains invalid data.

{
  "type": "https://developer.document360.com/errors/validation-error",
  "title": "Unprocessable Entity.",
  "status": 422,
  "detail": "One or more fields failed validation.",
  "instance": null,
  "trace_id": "req_abc123def456",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "message": "This field is required.",
      "field": "title",
      "details": null
    }
  ],
  "warnings": null
}

Expand All

object

RFC 7807 Problem Details response for V3 API errors. Content-Type: application/problem+json

type

string

URI reference identifying the error type (links to documentation).

Min length1

title

string

Short human-readable summary of the error type.

Min length1

status

integer (int32)

HTTP status code.

detail

string | null

Human-readable explanation specific to this occurrence.

instance

string | null

URI of the request that generated the error.

trace_id

string | null

Request trace identifier for correlation.

errors

Array of object (ApiError) | null

Structured list of specific errors (extension field).

object

Represents an error returned by the API.

code

string

Machine-readable error code (e.g. VALIDATION_ERROR, RESOURCE_NOT_FOUND).

Min length1

message

string

Human-readable error message.

Min length1

field

string | null

The request field that caused the error, if applicable.

details

string | null

Additional context about the error.

warnings

Array of object (ApiWarning) | null

Non-fatal warnings (extension field).

object

Represents a non-fatal warning from the API.

code

string

Machine-readable warning code.

Min length1

message

string

Human-readable warning message.

Min length1

429

Rate limit exceeded. Retry after the duration specified in the Retry-After header.

Headers

Retry-After

integer

Number of seconds to wait before retrying the request. Use exponential backoff with jitter for optimal retry behavior.

X-RateLimit-Limit

integer

The maximum number of requests allowed in the current time window. Limits are applied per API token per project.

X-RateLimit-Remaining

integer

The number of requests remaining in the current time window. When this reaches 0, subsequent requests will receive a 429 response.

X-RateLimit-Reset

integer

The UTC epoch timestamp (in seconds) when the current rate limit window resets.

Rate limit exceeded

Rate limit exceeded.

{
  "type": "https://developer.document360.com/errors/too-many-requests",
  "title": "Too Many Requests.",
  "status": 429,
  "detail": "Rate limit exceeded. Retry after the duration specified in the Retry-After header.",
  "instance": null,
  "trace_id": "req_abc123def456",
  "errors": [
    {
      "code": "TOO_MANY_REQUESTS",
      "message": "Rate limit exceeded. Retry after the duration specified in the Retry-After header.",
      "field": null,
      "details": null
    }
  ],
  "warnings": null
}

Expand All

object

RFC 7807 Problem Details response for V3 API errors. Content-Type: application/problem+json

type

string

URI reference identifying the error type (links to documentation).

Min length1

title

string

Short human-readable summary of the error type.

Min length1

status

integer (int32)

HTTP status code.

detail

string | null

Human-readable explanation specific to this occurrence.

instance

string | null

URI of the request that generated the error.

trace_id

string | null

Request trace identifier for correlation.

errors

Array of object (ApiError) | null

Structured list of specific errors (extension field).

object

Represents an error returned by the API.

code

string

Machine-readable error code (e.g. VALIDATION_ERROR, RESOURCE_NOT_FOUND).

Min length1

message

string

Human-readable error message.

Min length1

field

string | null

The request field that caused the error, if applicable.

details

string | null

Additional context about the error.

warnings

Array of object (ApiWarning) | null

Non-fatal warnings (extension field).

object

Represents a non-fatal warning from the API.

code

string

Machine-readable warning code.

Min length1

message

string

Human-readable warning message.

Min length1

500

An unexpected server error occurred.

Unexpected server error

Unexpected server error.

{
  "type": "https://developer.document360.com/errors/internal-error",
  "title": "Internal Server Error.",
  "status": 500,
  "detail": "An unexpected error occurred. Please try again or contact support.",
  "instance": null,
  "trace_id": "req_abc123def456",
  "errors": [
    {
      "code": "INTERNAL_SERVER_ERROR",
      "message": "An unexpected error occurred.",
      "field": null,
      "details": null
    }
  ],
  "warnings": null
}

Expand All

object

RFC 7807 Problem Details response for V3 API errors. Content-Type: application/problem+json

type

string

URI reference identifying the error type (links to documentation).

Min length1

title

string

Short human-readable summary of the error type.

Min length1

status

integer (int32)

HTTP status code.

detail

string | null

Human-readable explanation specific to this occurrence.

instance

string | null

URI of the request that generated the error.

trace_id

string | null

Request trace identifier for correlation.

errors

Array of object (ApiError) | null

Structured list of specific errors (extension field).

object

Represents an error returned by the API.

code

string

Machine-readable error code (e.g. VALIDATION_ERROR, RESOURCE_NOT_FOUND).

Min length1

message

string

Human-readable error message.

Min length1

field

string | null

The request field that caused the error, if applicable.

details

string | null

Additional context about the error.

warnings

Array of object (ApiWarning) | null

Non-fatal warnings (extension field).

object

Represents a non-fatal warning from the API.

code

string

Machine-readable warning code.

Min length1

message

string

Human-readable warning message.

Min length1

Was this article helpful?

What's Next

Get the top 5 most read articles ranked by read duration (not paginated).